Viewing Sessions

To initiate a view, the following RESTful operations should be performed as detailed in the Prizm Services Sample discussion.

POST ViewingSession

The first step for viewing a document is to request a viewing session Identification JSON string. The body of the request is to send useful information about the document to the Prizm Services service which helps identify the document that will be uploaded to the service for conversion to a web compatible viewing format. The object to be posted here is the ViewSessionProperties resource which contains several properties.

The origin property is a key pair dictionary to contain any useful arbitrary data about the document. The Prizm Services sample uses ipAddress, hostname, and sourceDocument for identification purposes, but any arbitrary data can be used that helps identify or characterizes the document.

The render property is important for storing information for client-side rendering. It stores rendering information for both the flash client and HTML client. For flash see the Basic Document Conversion Parameters on enterprise. For HTML5, the new Html5RenderProperties class object has properties to set output dpi resolution and whether raster output should always be used (no SVG format output).

The externalId property and tenantId should also be set. Typically, the externalId is a unique value which makes it easier to connect items in the server log to that which is in the caller’s log but is not used for any particular purpose and the same goes for tenantId. Please look at the Prizm Services sample for more information on using this RESTful API.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession

Parameters

None

Request Body

In the request body, supply a ViewingSessionProperties resource with the following optional properties:

Property Name	Value	Description
origin	List	A list of key-value pairs containing user-specific data. This is useful for tracking information pertinent to the request, like IP address, Host Name, and any other useful bits of information.
render	Nested Object	The object that describes rendering options.
render.flash	Nested Object	The object that describes rendering options for the Flash viewer.
render.flash.optimizationLevel	Integer	Specifies the optimization level used during SWF generation for the Flash viewer: 0 = No compression for text and images. 1 = Text is preserved while everything else is converted to JPEG compressed images. 2 = All content is converted into a single SWF, only links are preserved.
render.html5	Nested Object	The object that describes rendering options for the HTML5 viewer.
render.html5.alwaysUseRaster	Boolean	Forces Prizm Services to always provide raster image data to the HTML5 viewer instead of SVG, even if the client supports viewing SVG data.
render.html5.rasterResolution	Integer	Specifies the resolution to use for raster content generated by Prizm Services.
password	String	Specifies the password to open password-protected PDF documents.
serverCaching	String	This optional property determines whether or not the conversion output is cached for potential reuse by other viewing sessions. Valid values are: "full" means that the output will be cached on the server. (default) "none" means that the output will not be cached on the server. By default, the output of the document conversion process is cached on the server for potential reuse in future viewing sessions created to view the same document. This assumes that a document is likely to be viewed multiple times across different viewing sessions. If this is not the case (e.g., a new viewing session is always a new document), you can save disk space on the server by explicitly setting the serverCaching property to "none" to prevent the caching of the output on the server.
watermarkText	String	Specifies the text to use for watermarking as supported by the Flash viewer. This property is not currently used for the HTML5 viewer when displaying SVG content.
externalId	String	If the documentSource property is set to "api", empty, or is null, this property is not used by Prizm Services and can be used to store a value of your choosing for the viewing session. This value could be useful for identifying requests in Prizm Services log files or other purposes you find useful. If the documentSource property is set to "http" or "file", then this property must define the URL or local file path of the source document that Prizm Services will retrieve. See the How to Transfer Your Document to Prizm Services topic for more details.
tenantId	String	This is an ID for a tenant. Tenants are not a formal concept in this system and should be monitored and maintained in the calling system. However, having this data available will allow some optional behavior. For example, with this information, it would be possible to ensure some level of isolation between tenants.
attachmentIndex	Integer	Used for documents with attachment documents, like .MSG and .EML types. Otherwise, this value will typically be 0 for other document types.
attachmentDisplayName	String	Used for documents with attachment documents, like .MSG and .EML types. Provides the display name of the attachment.
countOfInitialPages	Integer	The default value is 0, which will cause Prizm Services to behave in its default manner converting all pages (running enterprise=3) of the document as soon as any page is requested. Setting countOfInitialPages to a value greater than 0 will instruct Prizm Services to use two separate enterprise=3 operations: one to convert pages 0 through n-1 (where "n" the supplied value) and a second conversion to process pages "n" through the end of the document. The second conversion will only occur when content that has not been converted is requested. This should allow the first "n" pages to be created and delivered to the client without forcing the entire document to be converted.
documentSource	String	This property tells Prizm Services how it should expect to get the source document for a viewing session. The following values are supported: "api" means that the document will be sent to Prizm Services using the PUT HTTP request. This is the default and will be used if this property is null or empty. "http" means that Prizm Services should download the source document from the URL provided in the "externalId" property. "file" means that Prizm Services should create a copy of the source document from the local file path provided in the "externalId" property. See the How to Transfer Your Document to Prizm Services topic for more details.
documentExtension	String	Defines the extension of the document specified in the externalId property. This property is only required if documentSource is "http" or "file" and the file name specified in externalId does not contain a valid document extension. If the file name specified inexternalId contains a valid extension for the document, this property can be left unset. The preceding "." should NOT be included in the extension value, otherwise an exception will be thrown and return 500 status from the POST HTTP request.
startConverting	String	This property determines when the process to generate pages for viewing is started. This property requires that documentSource is "http" or "file" and contentType is set to a valid value. Valid values are: "initialPages" means the process to generate pages for viewing is started during the initial POST /ViewingSession request. "none" means the process to generate pages for viewing is started later during a request to POST /ViewingSession/{id}/Notification/SessionStarted, GET /Page or GET /PageAttributes, whichever comes first.
contentType	String	This property sets the type of pages that are generated for viewing if startConverting is not "none". Valid values are: "png" means that PNG pages will be generated for viewing. "svg" means SVG pages will be generated for viewing. "svga" means SVG pages will be generated for viewing, but SVG will be optimized to reduce payload size. Note: "svga" is not supported by the Internet Explorer 10 browser. "swf" means SWF pages will be generated for viewing.

Response Body

If successful, this method returns the following properties:

Property Name	Value	Description
viewingSessionId	String	The ID for this new viewing session.

Example	Copy Code
POST http://localhost:18681/PCCIS/V1/ViewingSession

Example Response	Copy Code
{"viewingSessionId":"8091681f-15bf-4150-94a0-3ff7f2acd42d"}

PUT ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}

A document source is uploaded to the Prizm Services by writing the contents into the request stream using the viewing session ID from the previous viewing session ID request.

Http Method

PUT

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}

Parameters

ViewingSessionID	The ID of the viewing session associated with the request.
FileExtension	The extension representing the type of document being uploaded. This value should not include a '.' character prefix.

Request Body

In the request body, supply the document data to be uploaded.

Response Body

Empty.

Example	Copy Code
PUT //localhost:18681/PCCIS/V1/ViewingSession/ u8091681f-15bf-4150-94a0-3ff7f2acd42d/SourceFile?FileExtension=doc

Example Response	Copy Code
Empty

GET ViewingSession/u{ViewingSessionID}/SourceFile

Returns the original source document for a valid, active viewing session. The document returned will be an identical copy of the document originally provided to PCCIS; no conversions to other formats are supported.

The response will set the Content-Type header value to the registered MIME type associated with document extension provided with the original document. If a registered MIME type is not found, the value “application/octet-stream” is used.

Http Method

GET

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/SourceFile

Parameters

ViewingSessionID

The ID of the viewing session.

Request Body

None

Response Body

The document data, in its original format.

Example	Copy Code
GET /localhost:18681/PCCIS/V1/ViewingSession/ u8091681f-15bf-4150-94a0-3ff7f2acd42d/SourceFile

Example Response	Copy Code
200 OK Content-Type: application/msword [Document Data]

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

This RESTful API requests the Prizm Services service to begin conversion of the document to either HTML or Flash format. The body posted to the service will have an object which indicates the preference. The object property, viewer, will either be set to "HTML5" or "Flash".

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, supply an object with the following required property:

Property Name

Value

Description

viewer

String

Specify the type of viewer being used. The supported values are:

"HTML5"
"Flash"

Response Body

Empty.

Example	Copy Code
POST http://localhost:18681/PCCIS/V1/ViewingSession/ u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStarted.

Example Response	Copy Code
Empty

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

If the upload session fails (typically an exception is thrown), this RESTful API must be called to notify the Prizm Services that the upload cannot be completed and stop everything concerning the viewing session Id indicated. An error status and message is noted in the object posted.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, optionally supply a SessionStoppedProperties resource with the following optional properties:

Property Name	Value	Description
endUserMessage	String	A message suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped.
httpStatus	Integer	The http status suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped.
accusoftErrorNumber	Integer	A custom Accusoft error number that should be sent back to the end user to be returned if any attempt to use the session is made after the session has been stopped.
serverLogMessage	String	A message that should be placed into the server's log file when the session is stopped.

Response Body

Empty.

Example	Copy Code
POST http://localhost:18681/PCCIS/V1/ViewingSession/ u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStopped

Example Response	Copy Code
Empty